home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Contributed / SpriteWorld / Documentation / Add-On Docs / SWParticles < prev    next >
Encoding:
Text File  |  2000-10-06  |  4.1 KB  |  97 lines  |  [TEXT/ttxt]
  1. Usage
  2.  
  3. To use the particle routines in your own project, add SWParticles.c to your project, and #include SWParticles.h.
  4.  
  5. With just a few calls you can add some pretty spiffy effects to your SpriteWorld.  To set things up, call InitParticles, and install the appropriate postEraseCallBack and postDrawCallBack (depending on whether your animation is scrolling or non-scrolling). Then simply call NewParticle whenever you want to add a new particle to the animation. To run the animation, call UpdateParticlesInWindow or UpdateParticlesInScrollingWindow once each frame in your main animation loop.
  6.  
  7. Fix-point numbers
  8.  
  9. To get the fix-point values easily, use the type SWFixed and these macros:
  10.  
  11.     SWFixed SW_FLOAT2FIX(float x);
  12.     float SW_FIX2FLOAT(SWFixed x);
  13.  
  14.     SWFixed SW_INT2FIX(int x);
  15.     int SW_FIX2INT(SWFixed x);
  16.  
  17. But be aware that the float <-> fixed conversions will be slow, even on a PPC, as any conversion between floating point and integer will be slow.
  18.  
  19. You may safely add and subtract fixed-point numbers with each other. You may also use multiplication and division, provided that one of the numbers is fixed-point, and the other is a normal integer. For example, the following are all correct:
  20.  
  21. fixedNum = fixedNum / intNum;
  22. fixedNum = intNum / fixedNum;
  23. fixedNum = intNum * fixedNum;
  24.  
  25. The only danger here is that you might have overflow when doing multiplication, although this is unlikely, considering that the range of a SWFixed number is 8388607.255 through -8388608.255.
  26.  
  27. You don't have to include SWFixed.c unless you want the trig tables too.
  28. Then you must set them up with a call SWInitTrigTables.
  29.  
  30.  
  31. Function Reference
  32.  
  33. InitParticles
  34.  
  35. SW_FUNC OSErr InitParticles(long NumParticles, SWFixed Gravity)
  36.  
  37. Call this once when you start up.  Allocates space for the particle list. 
  38. NumParticles is the max number of particles to track.  Gravity is an amount applied to each particle every frame. You'll most likely want to use 1 or less. An error code will be returned if the memory allocation for the particle array fails.
  39.  
  40.  
  41. ClearParticles
  42.  
  43. SW_FUNC void ClearParticles( void );
  44.  
  45. Call this if you want to clear out the current particles.  It doesn't erase
  46. them from the screen though - you need to use
  47. SWCopyBackgroundToWorkArea(spriteWorldP) and
  48. SWUpdateSpriteWorld(spriteWorldP, true) to update the window.
  49.  
  50.  
  51. NewParticle
  52.  
  53. SW_FUNC void NewParticle(
  54.     unsigned long    color,
  55.     SWFixed    horizLoc,
  56.     SWFixed    vertLoc,
  57.     SWFixed    horizSpeed,
  58.     SWFixed    vertSpeed,
  59.     short    lifeRemaining);
  60.  
  61. Adds a new particle to the animation. 
  62. color is a color index.  Use Color2Index to convert from a rgb color to the index. 
  63. lifeRemaining tells the particle library how many frames the particle exists before being deleted. The particle will not be added if the particleArray is too full. (InitParticles defines the maximum number of particles you can have at any time.)
  64.  
  65.  
  66. EraseParticlesOffscreen / EraseParticlesScrollingOffscreen
  67.  
  68. SW_FUNC void EraseParticlesOffscreen( SpriteWorldPtr spriteWorldP );
  69. or for scrolling
  70. SW_FUNC void EraseParticlesScrollingOffscreen( SpriteWorldPtr spriteWorldP);
  71.  
  72. set that up with:
  73. SWSetPostEraseCallBack(spriteWorldP, EraseParticlesOffscreen);
  74.  
  75.  
  76. DrawParticlesOffscreen / DrawParticlesScrollingOffscreen
  77.  
  78. SW_FUNC void DrawParticlesOffscreen( SpriteWorldPtr spriteWorldP );
  79. or for scrolling 
  80. SW_FUNC void DrawParticlesScrollingOffscreen( SpriteWorldPtr spriteWorldP );
  81.  
  82. set that up with:
  83. SWSetPostDrawCallBack(spriteWorldP, DrawParticlesOffscreen);
  84.  
  85.  
  86. UpdateParticlesInWindow / UpdateParticlesInScrollingWindow
  87.  
  88. SW_FUNC void UpdateParticlesInWindow( SpriteWorldPtr spriteWorldP );
  89. or for scrolling
  90. SW_FUNC void UpdateParticlesInScrollingWindow( void );
  91. Call once in your animation loop to update the particles
  92.  
  93. You will want to set each of your Sprite's needsToBeDrawn flags to true when using particles, as the particles will leave "holes" in your Sprites if they move over idle Sprites.
  94.  
  95. -------------
  96.  
  97. These routines were originally written by Matthew Foodim (MatthewF@Panix.com), and updated by Anders F Björklund (afb@algonet.se) to do 16-bit and 32-bit, as well as fixed-point. Vern Jensen (Jensen@loop.com) cleaned up and optimized the particle engine and demos.